/*
 * 版权声明 (c) 2025 XXX科技有限公司
 *
 * 本软件及其相关文档文件受版权保护。未经版权所有者明确书面许可，任何单位或个人不得
 * 以任何形式复制、传播、修改、出售、出租、反向工程、反编译或利用本软件的任何部分。
 *
 * 对于任何违反本声明的行为，版权所有者保留追究法律责任的权利。
 */

#ifndef __MODULE_H__
#define __MODULE_H__
#include <string>
#include <utility>
#include <functional>
#include "utils/network.h"
#include "log.h"
#include "config.h"

// FIXME: 「Feature」模块化设计
/* ******************************* 模块化设计 *******************************
 *  服务模块（Service Modules）
 *    1. Service（服务）：强调模块提供长期运行的后台功能（如 "Agent Service"）。
 *    2. Daemon（守护进程）：在 Unix/Linux 系统中，指后台持续运行的进程。
 *    3. Worker（工作线程）：如果模块的核心是线程池或任务队列。
 *    4. Background Task（后台任务）：泛指非阻塞主线程的长期任务。
 *    5. Scheduler（调度器）：如果模块负责定时任务或事件调度。
 *    6. Task（任务）：如果模块是独立执行的任务，不长期驻留。
 *
 * 功能模块（Functional Modules）
 *    1. Library（库）：强调模块是可复用的代码集合（如 "Session Library"）。
 *    2. Utility（工具类）：如果模块提供辅助功能（如日志、加密等）。
 *    3. Component（组件）：泛指可插拔的软件单元（不区分主动/被动时常用）。
 *    4. Stateless Service（无状态服务）：如果模块是服务但无持久化状态。
 *    5. Middleware（中间件）：如果模块位于多个服务之间，提供通用功能。
 **************************************************************************/
#define MODULE_ROUTER "Router"       // 1. 路由模块
#define MODULE_BREADCAST "Breadcast" // 2. 广播模块
#define MODULE_SYNC "Sync"           // 3. 同步模块
#define MODULE_AGENT "Agent"         // 4. 代理模块
#define MODULE_SESSION "Session"     // 5. 会话模块
#define MODULE_RegCenter "RegCenter" // 6. 注册中心
#define MODULE_API "API"             // 7. API模块

/* **************************** 模块生命周期管理 ****************************
 *  说明:
 *    1. Constructor: 仅初始化成员变量，不访问外部资源，不执行复杂逻辑。
 *    2. Init: 		  准备必要资源或环境，不启动实际业务。
 *    3. Start: 	  启动业务逻辑（如线程、连接、注册等）。
 *    4. Stop: 		  终止业务、释放Start阶段资源。
 *    5. Destructor:  清理自身资源，不负责业务终止。
 *
 * 总结:
 * 构造和析构:			  [业务无关] 仅管理自身资源，不涉及具体业务。
 * Init、Start、Stop：	 [业务相关] 业务相关的初始化、启动和停止操作。
 **************************************************************************/
class Context; // 前向声明
class Module {
private:
	string module_name;

protected:
	// 引用上下文
	std::shared_ptr<Context> ctx;

public:
	Module()                          = delete;
	Module(const Module &)            = delete;
	Module &operator=(const Module &) = delete;
	Module(Module &&)                 = delete;
	Module &operator=(Module &&)      = delete;

	/// @brief 模块基类
	///  仅用于成员变量的初始化和基础资源分配，不访问外部资源或执行复杂逻辑(如启动线程、连接网络等)。
	/// @param ctx:   上下文
	/// @param name:  模块名称
	explicit Module(std::shared_ptr<Context> ctx, std::string name) : module_name(name), ctx(ctx) {}

	// 用于准备模块运行所需的资源和环境（如配置检查、分配缓冲区），但不进行实际的业务启动或外部服务连接。
	virtual bool Init() = 0; // 纯虚函数，子类必须实现

	// 负责真正启动模块业务（如启动线程、连接服务、注册回调），使模块进入工作状态。
	virtual void Start() {} // 普通函数，子类可以选择实现

	// 用于停止模块业务，回收Start阶段分配的资源，实现安全退出和清理。
	virtual void Stop() {} // 普通函数，子类可以选择实现

	// 仅负责释放构造和Init分配的资源，不应承担Stop应做的业务终止操作，避免耗时或复杂逻辑。
	virtual ~Module() = default;

	// 当前模块名称
	inline std::string ModuleName() const { return module_name; }
};
#endif //__MODULE_H__
